home *** CD-ROM | disk | FTP | other *** search
/ The PC-SIG Library 10 / The PC-Sig Library - Shareware for the IBM PC and Compatibles (PC-SIG)(Tenth Edition Disks 1-2804)(1991).iso / PC_SIGCD / 01 / 6 / DISK0162.ZIP / UTIL.DOC < prev    next >
Text File  |  1984-10-10  |  17KB  |  601 lines
  1.  
  2.  
  3.  
  4.                                    October 1984
  5.  
  6.         This  document  tells  how  to  use  the Structured BASIC program
  7.         debugger,  lister,  and  library  routines.  These utilities make
  8.         writing Structured BASIC programs easier. This manual assumes you
  9.         are familiar with MS DOS and Microsoft BASIC.
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.                               THE BASIC NECESSITIES                              THE BASIC NECESSITIES
  22.                              UTILITIES USER'S MANUAL                             UTILITIES USER'S MANUAL
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.                              Manual version:   1.12
  30.  
  31.                              Software version: 1.12
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.                                    Marty Franz
  48.  
  49.                      525 W. Walnut St., Kalamazoo, MI 49007
  50.  
  51.                                  (616) 344-1821
  52.  
  53.  
  54.  
  55.                (C) Copyright 1983 Marty Franz - All rights reserved
  56.  
  57.  
  58.  
  59.  
  60.  
  61.         100784112         Utilities User's Manual
  62.  
  63.  
  64.  
  65.         INTRODUCTION        INTRODUCTION
  66.  
  67.             The BASIC Necessities is a complete BASIC programming system
  68.         for the IBM Personal Computer.  It features a text editor for
  69.         entering and changing Structured BASIC statements, and a
  70.         preprocessor for converting Structured BASIC programs into BASIC
  71.         programs that can be executed on the PC.  The preprocessor and
  72.         editor User's Manuals describe these programs in detail.  This
  73.         manual concerns itself with several additional programs that can
  74.         make writing and debugging Structured BASIC programs easier:
  75.  
  76.             - LLIST.EXE, a program to list your Structured BASIC
  77.               source files on a printer with your choice of several
  78.               formatting options,
  79.  
  80.             - XREF.EXE, a cross-reference generator,
  81.  
  82.             - ENTAB, DETAB, and ARCH, convenient utility programs,
  83.  
  84.             - DEBUG.INC, a debugger module that lets you debug your
  85.               Structured BASIC programs at the procedure level, and
  86.  
  87.             - the files SCREEN.INC, CLS.INC, and INPUT.INC, library files
  88.               containing procedures that can be included into your
  89.               Structured BASIC programs to make your programming easier.
  90.  
  91.  
  92.         PROGRAM REQUIREMENTS        PROGRAM REQUIREMENTS
  93.  
  94.             To successfully use these utility programs, your need an IBM
  95.         PC, XT, or jr with:
  96.  
  97.             - at least 64KB of memory,
  98.  
  99.             - at least one single-sided diskette drive,
  100.  
  101.             - a color or monochrome adapter, and a monitor capable of
  102.               displaying 80-character lines,
  103.  
  104.             - MS DOS version 1.1 or 2.0, and
  105.  
  106.             - the files BASICA.COM or BASIC.COM.
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.                                                                          Page 2        100784112         Utilities User's Manual
  122.  
  123.  
  124.  
  125.         THE PROGRAM DEBUGGER        THE PROGRAM DEBUGGER
  126.  
  127.               The Structured BASIC program debugger is used during
  128.         development to trace Structured BASIC program execution at the
  129.         procedure level. (For more information about "procedures" and the
  130.         rest of the Structured BASIC language, please consult the
  131.         Structured BASIC User's Manual.)  By including the file DEBUG.INC
  132.         in your program during preprocessing, and using the DEBUG and
  133.         NODEBUG statements, you can perform these helpful functions when
  134.         you are testing your program from within BASIC:
  135.  
  136.             - you can see the execution of each procedure on the screen
  137.               as it is called by a DO or GOSUB statement,
  138.  
  139.             - you can set a trap in your program to stop when a certain
  140.               procedure is reached, (this is called a "breakpoint")
  141.  
  142.             - you can stop your program, exit into BASIC, print the
  143.               values of your variables, then resume execution again, and
  144.  
  145.             - you can dump the "stack" of procedures called whenever you
  146.               stop the program's execution.
  147.  
  148.  
  149.         USING THE DEBUGGER        USING THE DEBUGGER
  150.  
  151.             To use the program debugger, you need to include the file
  152.         DEBUG.INC into your Structured BASIC source program.  Then, you
  153.         must select the individual procedures to be debugged by using the
  154.         DEBUG and NODEBUG Structured BASIC statements.  Here's an
  155.         example:
  156.  
  157.  
  158.                  INCLUDE DEBUG.INC   'Include the debugger procedures.
  159.  
  160.                  DEBUG               'Turn on debugging.
  161.  
  162.                  PROCEDURE MAIN      'First procedure to be debugged.
  163.                      .
  164.                      .
  165.                  ENDPROC
  166.  
  167.                  PROCEDURE ...
  168.                      .               'More procedures to be debugged are
  169.                      .                here.
  170.                  ENDPROC
  171.  
  172.                  NODEBUG            'Turn off debugging.
  173.  
  174.                  INCLUDE SCREEN.INC  'Procedures here will not be
  175.                                       debugged.
  176.  
  177.  
  178.         The statements DEBUG and NODEBUG work just like a switch.  When
  179.         DEBUG is encountered, all the procedures following it will have
  180.  
  181.                                                                          Page 3        100784112         Utilities User's Manual
  182.  
  183.  
  184.         calls to debugger routines generated after their first and last
  185.         statements.  When NODEBUG is reached, this generation is turned
  186.         off.  Both DEBUG and NODEBUG must appear in a source file outside
  187.         a procedure.  When you run your program from BASIC, these extra
  188.         calls help the debugger determine where in execution is in the
  189.         program.
  190.  
  191.  
  192.         DEBUGGING IN BASIC        DEBUGGING IN BASIC
  193.  
  194.             After your program has been preprocessed with debugger
  195.         statements in it, it can be run from BASIC.  The debugger will
  196.         get control before procedure MAIN does, and will display a list
  197.         of available commands and prompt you for one with "debug:"
  198.         displayed on line 25 of the screen.  The commands you can use in
  199.         the debugger are:
  200.  
  201.                  X    to exit to BASIC with a STOP statement.  This
  202.                       allows you to print key variables in your program
  203.                       and list parts of your code.  The BASIC CONT
  204.                       command can be used to continue execution.
  205.  
  206.                  B    to have the debugger prompt you for a breakpoint.
  207.                       Enter the name of the procedure where you want the
  208.                       program to stop next.  If you don't want to stop at
  209.                       any procedures during execution, just press enter.
  210.  
  211.                  D    to display the names of the procedures currently
  212.                       active, along with their appropriate line numbers.
  213.                       This will be shown  enclosed by a frame in the
  214.                       upper right corner of your screen.  The topmost
  215.                       procedure in the list will be the one currently
  216.                       being executed, with the one below it being the one
  217.                       that called it, etc.  This can be used to help you
  218.                       trace the location of bugs in the program.
  219.  
  220.                  G    to resume execution of the program.
  221.  
  222.             As your program is running, the procedures being executed are
  223.         displayed on line 25 of the screen along with the line number
  224.         they start on.  You can stop execution of the program at any time
  225.         by pressing F10.  This will enter the debugger at the next
  226.         procedure encountered.
  227.  
  228.             Besides stopping at a breakpoint or by F10 on the keyboard,
  229.         the debugger is entered whenever a BASIC error is encountered.
  230.         The error message and line number will be displayed on line 25 of
  231.         the screen.  A line number of 65535 means the error happened in
  232.         direct mode.
  233.  
  234.             The debugger is in Structured BASIC source code and can be
  235.         changed for special needs.  You might want to do this if you are
  236.         developing programs that do a lot of color or graphics, since the
  237.         debugger assumes a text screen with 25 lines of 80 characters.
  238.         All of the debugger's variable definitions are contained in the
  239.         procedure DEBUG.SETUP, which is called before MAIN is when your
  240.  
  241.                                                                          Page 4        100784112         Utilities User's Manual
  242.  
  243.  
  244.         program is started.
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272.  
  273.  
  274.  
  275.  
  276.  
  277.  
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.                                                                          Page 5        100784112         Utilities User's Manual
  302.  
  303.  
  304.  
  305.         THE LLIST PROGRAM        THE LLIST PROGRAM
  306.  
  307.             The file LLIST.EXE on your Structured BASIC program disk is a
  308.         general-purpose print utility.  With it, you can print your
  309.         Structured BASIC source files, selecting any of several
  310.         formatting options.
  311.  
  312.             LLIST's syntax is similar to other MS DOS commands.  You must
  313.         supply it the name of the file you want to list, and additional
  314.         information through program "switches" to select any extra
  315.         formatting options.  LLIST's format is:
  316.  
  317.                  A>LLIST {/n /p /s /ln /wn /tn} file1 file2 ...
  318.  
  319.         Only a file name is required.  An extension of .SB is always
  320.         assumed.  You must put the switches before the names of the files
  321.         you want them to effect.  The switches control these options:
  322.  
  323.                  /n    omits page headings from the listing. Normally,
  324.                        your listing will have the filename, date, time,
  325.                        and page number at the top of each page.  The /n
  326.                        switch overrides this.
  327.  
  328.                  /p    is used when you are printing on single-sheet
  329.                        paper.  This will pause the program between pages
  330.                        so you can change sheets.  Press the "enter" key
  331.                        to continue with the next page.
  332.  
  333.                  /s    includes line numbers in the listing.  This switch
  334.                        is especially useful when you are debugging
  335.                        Structured BASIC programs and you need to match
  336.                        the line numbers of the preprocessor's error
  337.                        messages to the source statement.
  338.  
  339.                  /ln   sets the length of a page to n lines.  This is
  340.                        useful when printing on short forms or in
  341.                        compressed format.  Normally, this option is set
  342.                        to 60 lines/page.
  343.  
  344.                  /tn   sets tab stops every n columns.  Normally, you
  345.                        don't need to use this with Structured BASIC
  346.                        source files, since it is set by default to 4
  347.                        columns.  You might need to change this option for
  348.                        other languages like Pascal or C.  The maximum tab
  349.                        setting allowed is 10.
  350.  
  351.  
  352.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.  
  361.                                                                          Page 6        100784112         Utilities User's Manual
  362.  
  363.  
  364.                  /wn   sets the width of a page to n characters/line.
  365.                        Use this option for printing in compressed format,
  366.                        since the default is 80 characters/line.  Up to
  367.                        132 characters may be used.
  368.  
  369.                        Note:                       _____
  370.  
  371.                        This option is unaffected by the setting of the MS
  372.                        DOS "mode" command.
  373.  
  374.  
  375.             For normal use printing Structured BASIC source files, you
  376.         shouldn't need to use any of these options.  Here are some
  377.         examples of LLIST:
  378.  
  379.                  A>llist a:debug.inc
  380.  
  381.                       prints the file A:DEBUG.INC with standard tabs,
  382.                       page length (60 lines/page), and page width (80
  383.                       characters/line).
  384.  
  385.  
  386.                  A>llist /t2 /p screen.inc
  387.  
  388.                       prints SCREEN.INC from the A: drive with tabs set
  389.                       every 2 columns and a pause after every page.
  390.  
  391.  
  392.                  A>llist /w132 /l82 /p b:input.inc
  393.  
  394.                       prints the file INPUT.INC on drive B: with a page
  395.                       width of 132 characters/line and a page length of
  396.                       82 lines/page. The switch /p is used to that the
  397.                       paper can be manually advanced after every page.
  398.                       This combination of options can be used for
  399.                       extremely compressed listings on an Epson or IBM PC
  400.                       printer.
  401.  
  402.  
  403.  
  404.  
  405.  
  406.  
  407.  
  408.  
  409.  
  410.  
  411.  
  412.  
  413.  
  414.  
  415.  
  416.  
  417.  
  418.  
  419.  
  420.  
  421.                                                                          Page 7        100784112         Utilities User's Manual
  422.  
  423.  
  424.  
  425.         THE XREF PROGRAM        THE XREF PROGRAM
  426.  
  427.             The XREF.EXE program generates cross-references of your
  428.         Structured BASIC source files.  The cross-reference report
  429.         consists of a source listing with line numbers, followed by a
  430.         table showing all the variables, procedure names, and statement
  431.         labels in alphabetical order and a list of the line numbers that
  432.         use them.  XREF's format is:
  433.  
  434.                  A>XREF {/i /r /ln /wn /tn} file1 file2 ...
  435.  
  436.         Only a file name is required.  An extension of .SB is always
  437.         assumed.  You must put the switches before the names of the files
  438.         you want them to effect.  The switches control these options:
  439.  
  440.                  /i    cross references any INCLUDE files referenced in
  441.                        the file.  This option can generate a lot of
  442.                        listing.
  443.  
  444.                  /r    Includes the names of reserved words (OPEN, IF,
  445.                        PRINT, etc.) in the report.  A useful option when
  446.                        resolving variable name conflicts or converting
  447.                        programs from other versions of BASIC.
  448.  
  449.                  /ln   sets the length of a page to n lines.  This is
  450.                        useful when printing on short forms or in
  451.                        compressed format.  Normally, this option is set
  452.                        to 60 lines/page.
  453.  
  454.                  /tn   sets tab stops every n columns.  Normally, you
  455.                        don't need to use this with Structured BASIC
  456.                        source files, since it is set by default to 4
  457.                        columns.  You might need to change this option for
  458.                        other languages like Pascal or C.  The maximum tab
  459.                        setting allowed is 10.
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.  
  470.  
  471.  
  472.  
  473.  
  474.  
  475.  
  476.  
  477.  
  478.  
  479.  
  480.  
  481.                                                                          Page 8        100784112         Utilities User's Manual
  482.  
  483.  
  484.                  /wn   sets the width of a page to n characters/line.
  485.                        Use this option for printing in compressed format,
  486.                        since the default is 80 characters/line.  Up to
  487.                        132 characters may be used.
  488.  
  489.                        Note:                       _____
  490.  
  491.                        This option is unaffected by the setting of the MS
  492.                        DOS "mode" command.
  493.  
  494.  
  495.  
  496.  
  497.  
  498.  
  499.  
  500.  
  501.  
  502.  
  503.  
  504.  
  505.  
  506.  
  507.  
  508.  
  509.  
  510.  
  511.  
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.  
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.  
  536.  
  537.  
  538.  
  539.  
  540.  
  541.                                                                          Page 9        100784112         Utilities User's Manual
  542.  
  543.  
  544.  
  545.         SAMPLE LIBRARY FILES        SAMPLE LIBRARY FILES
  546.  
  547.             The files SCREEN.INC, CLS.INC, and INPUT.INC on the
  548.         Structured BASIC program disk contain several useful procedures
  549.         for handling screen input and output.
  550.  
  551.             SCREEN.INC contains routines for drawing boxes and frames on
  552.         the screen, putting status messages on line 24, and drawing
  553.         titles and headings.
  554.  
  555.             CLS.INC has an assembly language routine and two procedures
  556.         that make clearing areas on the screen from your programs much
  557.         faster.  (Prior to this, you had to output blank strings to clear
  558.         several lines.  This was very slow and made screen-oriented
  559.         programs slow as a result.)
  560.  
  561.             INPUT.INC contains routines for getting strings with INKEY$,
  562.         reading a single character from the keyboard, and simulating a
  563.         blinking cursor under program control.
  564.  
  565.             These library files can be included in your programs with the
  566.         statements:
  567.  
  568.                  INCLUDE SCREEN.INC (automatically includes CLS.INC)
  569.  
  570.         and
  571.  
  572.                  INCLUDE INPUT.INC
  573.  
  574.             Descriptions of the routines can be found in the files
  575.         themselves.  Studying them is also a good way to learn more about
  576.         using Structured BASIC. The sample Structured BASIC programs
  577.         CHARS.SB, ATTRIB.SB and SDIR.SB all make use of these
  578.         procedures.
  579.  
  580.  
  581.  
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.  
  601.                                                                         Page 10        100784112